package com.kexilo.dict.service;

import com.kexilo.dict.domain.DictData;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * 字典服务接口
 * 定义了字典数据操作的抽象接口，不依赖任何具体实现
 * 
 * @author Kexilo
 */
public interface DictService {
    
    /**
     * 根据字典类型查询字典数据
     * 
     * @param dictType 字典类型
     * @return 字典数据列表
     */
    List<DictData> selectDictDataByType(String dictType);
    
    /**
     * 异步根据字典类型查询字典数据
     * 
     * @param dictType 字典类型
     * @return 字典数据列表的异步结果
     */
    CompletableFuture<List<DictData>> selectDictDataByTypeAsync(String dictType);
    
    /**
     * 批量根据字典类型查询字典数据
     * 
     * @param dictTypes 字典类型列表
     * @return 字典类型和对应数据的映射
     */
    Map<String, List<DictData>> selectDictDataByTypes(List<String> dictTypes);
    
    /**
     * 根据字典类型和字典值查询字典标签
     * 
     * @param dictType 字典类型
     * @param dictValue 字典值
     * @return 字典标签
     */
    String selectDictLabel(String dictType, String dictValue);
    
    /**
     * 根据字典类型和字典标签查询字典值
     * 
     * @param dictType 字典类型
     * @param dictLabel 字典标签
     * @return 字典值
     */
    String selectDictValue(String dictType, String dictLabel);
    
    /**
     * 查询所有字典类型
     * 
     * @return 字典类型列表
     */
    List<String> selectDictTypeAll();
    
    /**
     * 刷新字典缓存
     * 
     * @param dictType 字典类型，为空时刷新所有
     */
    void refreshCache(String dictType);
    
    /**
     * 预热字典缓存
     * 
     * @param dictTypes 需要预热的字典类型列表，为空时预热所有
     */
    void warmupCache(List<String> dictTypes);
    
    /**
     * 检查字典值是否存在
     * 
     * @param dictType 字典类型
     * @param dictValue 字典值
     * @return 是否存在
     */
    boolean exists(String dictType, String dictValue);
    
    /**
     * 获取默认字典值
     * 
     * @param dictType 字典类型
     * @return 默认字典数据，如果没有则返回null
     */
    DictData getDefault(String dictType);
    
    /**
     * 获取启用状态的字典数据
     * 
     * @param dictType 字典类型
     * @return 启用的字典数据列表
     */
    List<DictData> selectEnabledDictDataByType(String dictType);
    
    /**
     * 根据字典类型查询数据并转换为Map
     * 
     * @param dictType 字典类型
     * @return 字典值->标签的映射
     */
    Map<String, String> selectDictMap(String dictType);
    
    /**
     * 根据字典类型查询数据并转换为反向Map
     * 
     * @param dictType 字典类型
     * @return 字典标签->值的映射
     */
    Map<String, String> selectDictReverseMap(String dictType);
    
    /**
     * 检查服务是否可用
     * 
     * @return 是否可用
     */
    boolean isAvailable();
    
    /**
     * 获取缓存统计信息
     * 
     * @return 缓存统计信息
     */
    Map<String, Object> getCacheStats();
    
    /**
     * 清除所有缓存
     */
    void clearAllCache();
    
    /**
     * 获取服务名称
     * 
     * @return 服务名称
     */
    default String getServiceName() {
        return this.getClass().getSimpleName();
    }
    
    /**
     * 获取服务版本
     * 
     * @return 服务版本
     */
    default String getServiceVersion() {
        return "1.0.0";
    }
    
    /**
     * 字典数据变更通知（可扩展用于数据同步）
     * 
     * @param dictType 字典类型
     * @param operation 操作类型：CREATE, UPDATE, DELETE
     * @param dictData 字典数据
     */
    default void notifyDataChange(String dictType, String operation, DictData dictData) {
        // 默认实现为空，具体实现类可以覆盖此方法
    }
}
